Aminet 28

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / util / shell / ViNCEd.lha / ViNCEd / Include / Autodocs / vnc.doc < prev

Wrap

Text File | 1998-08-22 | 116KB | 3,659 lines

TABLE OF CONTENTS vnc.library/--Background-- vnc.library/VNCInputHandler vnc.library/VNCImInputHandler vnc.library/VNCRawKeyConvert vnc.library/SwitchTABExpansion vnc.library/HandleTabExpansion vnc.library/AbortTabExpansion vnc.library/LockWindow vnc.library/UnlockWindow vnc.library/FindCNWindow vnc.library/UnFindCNWindow vnc.library/GetVNCPrefs vnc.library/GetVNCDefaultPrefs vnc.library/LoadPrefsFrom vnc.library/SavePrefs vnc.library/SavePrefsTo vnc.library/UsePrefs vnc.library/SetWindowPrefs vnc.library/GetWindowPrefs vnc.library/AllocPrefsBuffer vnc.library/FreePrefsBuffer vnc.library/List2Prefs vnc.library/Prefs2List vnc.library/FreeMacroList vnc.library/SendRequestPattern vnc.library/SendWindowOpens vnc.library/SendWindowCloses vnc.library/SendWindowQuit vnc.library/VNCRequestFile vnc.library/CtrlZSuspend vnc.library/VNCUniqueID vnc.library/GetNodeN vnc.library/AllocEdMem vnc.library/FreeEdMem vnc.library/AllocLine vnc.library/FreeLine vnc.library/NotifyChOwner vnc.library/NotifyClearScreen vnc.library/VNCAToI vnc.library/VNCHToI vnc.library/VNCStrToL vnc.library/VNCIToA vnc.library/VNCSPrintf vnc.library/VNCStrCmp vnc.library/VNCStrICmp vnc.library/VNCToUpper vnc.library/ConvertWindowTitle vnc.library/FindCloseMacro vnc.library/PrintSuspend vnc.library/QueueOwnerLine vnc.library/PutLineData vnc.library/SendAsyncPacket vnc.library/AllocAsyncPacket vnc.library/VNCDoPacket vnc.library/Foreground vnc.library/Background vnc.library/ConvertString vnc.library/PoolCreateExtIO vnc.library/PoolCreateStdIO vnc.library/PoolDeleteExtIO vnc.library/PoolDeleteStdIO vnc.library/PoolCreatePort vnc.library/PoolDeletePort vnc.library/VNCFOpen vnc.library/VNCFClose vnc.library/VNCFRead vnc.library/VNCFWrite vnc.library/VNCOneRequester vnc.library/VNCTwoRequester vnc.library/GetHistory vnc.library/PutHistory vnc.library/GetScreen vnc.library/PutScreen vnc.library/NameOfFunction vnc.library/NameOfKey vnc.library/InstallGlobalHooks vnc.library/--Background-- vnc.library/--Background-- PURPOSE: The vnc.library is the main library of the ViNCEd console handler. Its purpose is to manage the preferences of the handler, as well as provide interface functions to commonly used features as saving or loading the review buffer or the command history. It contains also functions to identify an I/O stream as ViNCEd stream or to find the intuition window related to such a stream. It provides also functions to give back this pointer to allow iconification or closing of that window. Various vectors in this library serve more as "patchable hook" then "callable functions", i.e. they can be patched to replace various ViNCEd features as the TAB expansion or the keyboard parser. It contains furthermore miscellaneous functions used by the SetVNC preferences editor which are open to other applications as well. Last but not least, it contains job control functions which allow user applications to put their programs to foreground or background. vnc.library/VNCInputHandler vnc.library/VNCInputHandler NAME VNCInputHandler - collect input events, send them to windows SYNOPSIS ievent = VNCInputHandler ( ievent , vncbase ); d0 a0 a1 struct InputEvent * VNCInputHandler ( struct InputEvent *, struct VNCLibrary *); FUNCTION Collects a linked list of input events, and sends the information to the open ViNCEd windows. INPUTS ievent - a linked list of InputEvents. vncbase - a pointer to the vnc.library, must be passed in a1 for this function. RETURNS the input event passed in. NOTES This function is called as a part of the ViNCEd input handler. Input events should be usually made available thru the input device and not by calling this function. BUGS SEE ALSO input.device, VNCImInputHandler() vnc.library/VNCImInputHandler vnc.library/VNCImInputHandler NAME VNCImInputHandler - collect input events, send them to windows SYNOPSIS ievent = VNCImInputHandler ( ievent , vncbase ); d0 a0 a1 struct InputEvent * VNCImInputHandler ( struct InputEvent *, struct VNCLibrary *); FUNCTION Collects a linked list of input events, and sends the information to the open ViNCEd windows. INPUTS ievent - a linked list of InputEvents. vncbase - a pointer to the vnc.library, must be passed in a1 for this function. RETURNS the input event passed in. NOTES This function is called as a part of the ViNCEd input handler. The only difference between this function and VNCInputHandler() is that this is the "immediate input handler" which hooks into the input handler chain in front of the intuition input handler, whereas VNCInputHandler() hooks in behind intuition. The reason for providing two input handler functions is to have the timer events available which are usually swallowed by the intuition input handler, but needed by ViNCEd. Input events should be usually made available thru the input device and not by calling this function. BUGS SEE ALSO input.device, VNCInputHandler() vnc.library/VNCRawKeyConvert vnc.library/VNCRawKeyConvert NAME VNCRawKeyConvert - convert raw keycodes to CSI/ESC/ASCII sequences SYNOPSIS converted = VNCRawKeyConvert ( kmrequest ) d0 a0 LONG VNCRawKeyConvert ( struct KeymapRequest * ) FUNCTION Convert an input event, pointed to by the KeymapRequest structure into a sequence of CSI codes or ASCII codes, pass back the number of characters in the buffer, or -1 if the buffer overrun. This function will make use of the ViNCEd extended CSI sequences if the flags in the KeymapRequest structure say so. INPUTS kmrequest - a pointer to the following structure: struct KeymapRequest { struct InputEvent *kmr_Event; struct Keymap *kmr_Keymap; struct ExtMap *kmr_ExtMap; ULONG kmr_Flags; char *kmr_Buffer; ULONG kmr_Length; ULONG kmr_Qualifier; ULONG kmr_ExtFlags; }; kmr_Event: the input event to process. This is only allowed to be a single input event, not a chain of input events. It MUST be of type IECLASS_RAWKEY. kmr_Keymap: a pointer to a standard console.device keymap to use for conversion of non-ViNCEd specific keys. kmr_ExtMap: a pointer to the ViNCEd extension of a keymap, found in the preferences, for example. kmr_Flags: a set of flags, defined as follows: KMF_EXTENDED: Reply extended ViNCEd CSI sequences as well. KMF_NUMLOCK: NumLock is active. You've to keep trace of this flag yourself. kmr_Buffer: the output buffer to place the characters in. kmr_Length: the size of this buffer. kmr_Qualifier: initialize to zero. kmr_ExtFlags: initialize to zero. RETURNS the number of characters put into the output buffer, or -1 if the buffer overrun. Furthermore, the following fields of the structure are set for you: kmr_Qualifier: the keyboard qualifier set in the input event. kmr_ExtFlags: the following flags can be made use of: (meaning: there are more you should not depend on) VPKF_NOSCROLL this key shall not snap back the window contents VPKF_NOTABXQ this key shall not terminate a TAB expansion VPKF_ASCII this key was found by an ASCII match and not a raw key code match VPKF_XTENDED this is a ViNCED extended function VPKF_IMMEDIATE this function must evaluate immedate, even if the type ahead buffer is active. NOTES BUGS SEE ALSO devices/keymap, vnc/prefs.h, the ViNCEd guide vnc.library/SwitchTABExpansion vnc.library/SwitchTABExpansion NAME SwitchTABExpansion - toggle the TAB expansion on/off SYNOPSIS success = SwitchTABExpansion ( cn, onoff ) d0 a5 d0 LONG SwitchTABExpansion ( struct ViNCWindow *, LONG ) success = SwitchTABExpansion_CN ( onoff ) d0 d0 LONG SwitchTABExpansion_CN ( LONG ) FUNCTION Toggle the TAB expansion on or off. INPUTS cn - a pointer to the ViNCWindow structure describing the ViNCEd window. This structure MUST HAVE BE LOCKED with LockCNWindow() before if you call this. See NOTES below. onoff - A boolean flag indicating whether expansion should be allowed or not. RESULTS a boolean success/failure indicator. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. You usually DO NOT want to call this function. It is provided to allow an alternative TAB expansion to hook in here. It is, however, called by the library itself in case the TAB expansion must be disabled or enabled. BUGS SEE ALSO LockWindow(), vnc/window.h vnc.library/HandleTabExpansion vnc.library/HandleTabExpansion NAME HandleTabExpansion - launch a TAB expansion SYNOPSIS success = HandleTabExpansion ( cn, len, pos, dir, buf, owner) d0 a5 d0 d1 d4 a0 a1 LONG HandleTabExpansion ( struct ViNCWindow *, ULONG, ULONG, ULONG, ULONG, char *, struct ViOwner *) success = HandleTabExpansion_CN ( len, pos, dir, buf, owner) LONG HandleTabExpansion_CN ( ULONG, ULONG, ULONG, char *, struct ViOwner *) FUNCTION Run a TAB expansion asynchronously in background on the provided information. Reinsert the expansion into the VINCEd window specified by "cn". INPUTS cn - a pointer to the ViNCEd main structure to handle. MUST be LOCKED with LockWindow(). len - the length of the line with user data to be expanded. pos - the position of the cursor within this buffer. Zero is the leftmost position. It is allowed in the range of 0..len. dir - direction/type information of which TAB function to use. 0,1: first Tab function, forwards resp. backwards 2,3: second Tab function, ... 10,11: sixth Tab function. More might be defined in the future. buf - buffer with the data to be expanded. This is the FULL line of user inputs only. All printed characters have already been filtered out. "pos" is the cursor position relative to the FILTERED data. owner - pointer to the ViNCEd owner structure where the current directory to look at should be extracted from. ViNCEd *tries* to make sure that this owner is stable and does not go away as long as the expansion is running. RESULTS a boolean success indicator whether the tab expansion could be launched successfully. It DOES NOT indicate whether the expansion worked or not. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. You usually DO NOT want to call this function. It is provided to allow an alternative TAB expansion to hook in here. It is, however, called by the library itself to launch the TAB expansion. Note again that this call is asynchronous. SEE ALSO LockWindow(), vnc/owner.h, vnc/window.h vnc.library/AbortTabExpansion vnc.library/AbortTabExpansion NAME AbortTabExpansion - try to cancel a running expansion SYNOPSIS success = AbortTabExpansion ( cn ) d0 a5 LONG AbortTabExpansion ( struct ViNCWindow * ) success = AbortTabExpansion_CN ( ) d0 LONG AbortTabExpansion_CN ( VOID ) FUNCTION Tries to cancel an already running Tab expansion. However, this routine may fail to do so in case the user opened a TAB expansion requester which cannot aborted due to system limitations. It will return -1 even in this case. INPUTS cn - a pointer to the ViNCEd window in which the TAB expansion is taking place. MUST BE LOCKED before calling this routine with LockWindow(). RESULTS -1 if the abort signal was send successfully. This DOES NOT mean that the expansion was aborted successfully, however. 0 on failure. 1 if the tab expansion was disabled. No signal is send in this case. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. You usually DO NOT want to call this function. It is provided to allow an alternative TAB expansion to hook in here. It is, however, called by the library itself in case the TAB expansion must be aborted. BUGS SEE ALSO LockWindow(), vnc/window.h vnc.library/LockWindow vnc.library/LockWindow NAME LockWindow - arbitrate exclusive access to a ViNCEd window SYNOPSIS LockWindow ( cn ) a5 VOID LockWindow ( struct ViNCWindow * ) LockWindow_CN ( ) VOID LockWindow_CN ( VOID ) FUNCTION Arbitrate exclusive access rights to the given ViNCEd main structure. By calling this function, the handler part of ViNCEd, as well as any other task is not allowed to modify any part of this structure. INPUTS cn - a pointer to the ViNCWindow structure, the main structure of ViNCEd. RESULTS NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window for most functions that require a pointer to this structure. Don't hold this lock permanently. DO NOT send any Dos I/O requests while you're holding this lock since this results in a deadlock. The handler part of ViNCEd will not be able to operate as long as you're holding this lock. Call UnlockWindow() to release the control. This call DOES nest! Assembler programmers might note that this call does not modify any registers, but it requires the a5 (and a6) register to be setup correctly. BUGS SEE ALSO UnlockWindow(), vnc/window.h vnc.library/UnlockWindow vnc.library/UnlockWindow NAME UnlockWindow - release access from a ViNCEd window SYNOPSIS UnlockWindow ( cn ) a5 VOID UnlockWindow ( struct ViNCWindow * ) UnlockWindow_CN ( ) VOID UnlockWindow_CN ( VOID ) FUNCTION Release access from the given ViNCEd main structure. INPUTS cn - a pointer to the ViNCWindow structure, the main structure of ViNCEd. RESULTS NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window for most functions that require a pointer to this structure. This call NESTS. Every call to UnlockWindow() must match one and exactly one call to LockWindow(). Assembler programmers might note that this call does not modify any registers, but it requires the a5 (and a6) register to be setup correctly. BUGS SEE ALSO LockWindow(), vnc/window.h vnc.library/FindCNWindow vnc.library/FindCNWindow NAME FindCNWindow - locate a ViNCEd window related to a file handle. SYNOPSIS cn = FindCNWindow ( file ) d0 d1 struct ViNCWindow * FindCNWindow ( BPTR ) FUNCTION This library function finds the ViNCEd main structure related to a file handle, as returned by the Open() function of the dos.library and required by other dos functions. Related to this operation, a closed intuition window will pop-open by this called and is not allowed to be iconified or closed until UnFindCNWindow() is called. INPUTS a BPTR to a file handle, describing the stream to the ViNCEd handler. RESULTS Either the pointer to the ViNCEd main window, or NULL if the stream is not a ViNCEd file. This call will also open the intuition window of the ViNCEd stream. NOTES You MUST call UnFindCNWindow() as soon as you don't need the intuition window any more. The ViNCEd main structure will not go away as long as you keep the stream open, but the intuition window may. EVERY CALL TO FindCNWindow() returning non-NULL must be matched by one and exactly one call to UnFindCNWindow(). You MUST NOT call UnFindCNWindow() if FindCNWindow() returned NULL. SEE ALSO UnFindCNWindow(), Open(), vnc/window.h, the ViNCEd guide vnc.library/UnFindCNWindow vnc.library/UnFindCNWindow NAME UnFindCNWindow - reallow iconification of a ViNCEd stream. SYNOPSIS UnFindCNWindow ( file ) d1 VOID UnFindCNWindow ( BPTR ) FUNCTION This library function undoes the side effect of FindCNWindow() and allows iconification and closing of the intuition window attachted to a ViNCEd stream. MUST BE CALLED if FindCNWindow() returned non-NULL. INPUTS a BPTR to a file handle, describing the stream to the ViNCEd handler. RESULTS NOTES You MUST call UnFindCNWindow() as soon as you don't need the intuition window any more. The ViNCEd main structure will not go away as long as you keep the stream open, but the intuition window may. EVERY CALL TO FindCNWindow() returning non-NULL must be matched by one and exactly one call to UnFindCNWindow(). You MUST NOT call UnFindCNWindow() if FindCNWindow() returned NULL. SEE ALSO FindCNWindow(), vnc/window.h, the ViNCEd guide vnc.library/GetVNCPrefs vnc.library/GetVNCPrefs NAME GetVNCPrefs - read the global preferences database SYNOPSIS size = GetVNCPrefs ( buffer , size ) d0 a0 d0 ULONG GetVNCPrefs ( struct VNCPrefs * , LONG ) FUNCTION Loads the globaly active preferences of ViNCEd. These need not to be the preferences of any window active, but the prefs that will be used by default if a new window opens. INPUTS buffer - the VNCPrefs structure allocated by AllocPrefsBuffer. size - must be set to -1. RESULTS the size of the preferences structure filled in. Should be usually ignored, this call CANNOT fail. NOTES The size parameter is only provided for backwards compatibility to VNC 2.xx and below. Passing any buffer in except those allocated by AllocPrefsBuffer, or using any other size than -1 is discouraged. SEE ALSO GetVNCDefaultPrefs(), LoadPrefsFrom(), vnc/Prefs.h vnc.library/GetVNCDefaultPrefs vnc.library/GetVNCDefaultPrefs NAME GetVNCDefaultPrefs - read the factory default preferences SYNOPSIS size = GetVNCDefaultPrefs ( buffer , size ) d0 a0 d0 ULONG GetVNCDefaultPrefs ( struct VNCPrefs * , LONG ) FUNCTION Loads the factory default preferences of ViNCEd. These are the defaults ViNCEd will use if no other preferences are available. INPUTS buffer - the VNCPrefs structure allocated by AllocPrefsBuffer. size - must be set to -1. RESULTS the size of the preferences structure filled in. Should be usually ignored, this call CANNOT fail. NOTES The size parameter is only provided for backwards compatibility to VNC 2.xx and below. Passing any buffer in except those allocated by AllocPrefsBuffer, or using any other size than -1 is discouraged. SEE ALSO GetVNCPrefs(), LoadPrefsFrom(), vnc/Prefs.h vnc.library/LoadPrefsFrom vnc.library/LoadPrefsFrom NAME LoadPrefsFrom - load the preferences from an external file SYNOPSIS size = LoadPrefsFrom ( buffer, size, filename ) d0 a0 d0 a1 ULONG LoadPrefsFrom ( struct VNCPrefs * , LONG , char * ) FUNCTION Load the ViNCEd preferences from an external file and place them in a buffer. Except that, the loaded preferences are not used for anything else. INPUTS buffer - the VNCPrefs structure allocated by AllocPrefsBuffer. size - must be set to -1. filename - the name of the file to load the preferences from. RESULTS the size of the preferences structure filled in, or zero in case of a failure. A secondary result code can be obtained by IoErr() in this case. NOTES The size parameter is only provided for backwards compatibility to VNC 2.xx and below. Passing any buffer in except those allocated by AllocPrefsBuffer, or using any other size than -1 is discouraged. This routine is able to parse (and correct) all preferences structures used so far, starting with versions 1 of VNC 1.xx up to the ASCII prefs file of version 3.60. This compatibility might be removed in a future version. Not all preferences settings of older versions will be respected, however. SEE ALSO GetVNCDefaultPrefs(), GetVNCPrefs(), IoErr(), vnc/Prefs.h vnc.library/SavePrefs vnc.library/SavePrefs NAME SavePrefs - save the preferences to the default location SYNOPSIS success = SavePrefs ( buffer , size ) d0 a0 d0 LONG SavePrefs ( struct VNCPrefs * , LONG ) FUNCTION Save the ViNCEd preferences to the default location in the ENVARC: drawer. This DOES NOT mean that the preferences become active. Hence, this does NOT include the UsePrefs() function. INPUTS buffer - the VNCPrefs structure allocated by AllocPrefsBuffer and filled in by you. size - must be set to -1. RESULTS a boolean success/failure indicator. A secondary result code can be obtained by IoErr() in case of failure. NOTES The size parameter is only provided for backwards compatibility to VNC 2.xx and below. Passing any buffer in except those allocated by AllocPrefsBuffer, or using any other size than -1 is discouraged. This routine will always save the preferences in the new ASCII format 3.3; hence, they won't be available for older versions of ViNCEd. The location this file is saved to is ENVARC:ViNCEd.Prefs, but don't take this for granted. To read the global preferences, use the GetVNCPrefs() routine. SEE ALSO SavePrefsTo(), UsePrefs(), GetVNCPrefs(), IoErr(), vnc/Prefs.h vnc.library/SavePrefsTo vnc.library/SavePrefsTo NAME SavePrefsTo - save the preferences to a given file name SYNOPSIS success = SavePrefsTo ( buffer , size , filename ) d0 a0 d0 a1 LONG SavePrefsTo ( struct VNCPrefs * , LONG , char * ) FUNCTION Save the ViNCEd preferences to the given location. This DOES NOT mean that the preferences become active. This function does not build an icon for the preferences. INPUTS buffer - the VNCPrefs structure allocated by AllocPrefsBuffer and filled in by you. size - must be set to -1. filename - the name of the file to save the preferences under. RESULTS a boolean success/failure indicator. A secondary result code can be obtained by IoErr() in case of failure. NOTES The size parameter is only provided for backwards compatibility to VNC 2.xx and below. Passing any buffer in except those allocated by AllocPrefsBuffer, or using any other size than -1 is discouraged. This routine will always save the preferences in the new ASCII format 3.3; hence, they won't be available for older versions of ViNCEd. SEE ALSO UsePrefs(), SavePrefsTo(), GetVNCPrefs(), IoErr(), vnc/Prefs.h vnc.library/UsePrefs vnc.library/UsePrefs NAME UsePrefs - make the preferences globally available SYNOPSIS success = UsePrefs ( buffer , size ) d0 a0 d0 LONG UsePrefs ( struct VNCPrefs * , LONG ) FUNCTION Install the preferences in the ViNCEd global database. This DOES NOT include that the prefences are installed in all open windows. It makes the preferences only available for all windows that are about to open after the preferences have been installed. INPUTS buffer - the VNCPrefs structure allocated by AllocPrefsBuffer and filled in by you. size - must be set to -1. RESULTS Non-null for success or zero on failure. A secondary result code can be obtained by IoErr() in case of failure. NOTES The size parameter is only provided for backwards compatibility to VNC 2.xx and below. Passing any buffer in except those allocated by AllocPrefsBuffer, or using any other size than -1 is discouraged. It is not guaranteed that the preferences will be made available immediately. There might be a delay of several seconds for the new prefs to become active. This routine works differently, depending on the Os version. For Os 1.3 or below, the preferences are simply copied to the ViNCEd library base. For 2.0 or above, it saves the preferences in ENV:. It's part of the VNC supervisor task to load it from there and to make them available. Do not depend on this information, however. It's likely that the 1.3 compatibility will be removed in the 3.70 release. SEE ALSO SavePrefs(), SavePrefsTo(), GetVNCPrefs(), IoErr(), vnc/Prefs.h vnc.library/SetWindowPrefs vnc.library/SetWindowPrefs NAME SetWindowPrefs - set the preferences for a specific ViNCWindow SYNOPSIS success = SetWindowPrefs ( cn , buffer , size ) d0 a5 a0 d0 LONG SetWindowPrefs ( struct ViNCWindow , struct VNCPrefs * , LONG ) success = SetWindowPrefs_CN ( buffer, size ) d0 a0 d0 LONG SetWindowPrefs_CN ( struct VNCPrefs * , LONG ) FUNCTION Set the preferences of a given ViNCEd window, locally. INPUTS cn - A pointer to the ViNCEd main structure. Need not to be locked here. buffer - the VNCPrefs structure, allocated by AllocPrefsBuffer() and filled by you. size - must be set to -1 RESULTS zero for failure and non-zero for success. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. SEE ALSO GetWindowPrefs(), AllocPrefsBuffer(), vnc/Prefs.h vnc.library/GetWindowPrefs vnc.library/GetWindowPrefs NAME GetWindowPrefs - get the preferences of a specific ViNCWindow SYNOPSIS success = GetWindowPrefs ( cn , buffer , size ) d0 a5 a0 d0 LONG GetWindowPrefs ( struct ViNCWindow , struct VNCPrefs * , LONG ) success = GetWindowPrefs_CN ( buffer, size ) d0 a0 d0 LONG GetWindowPrefs_CN ( struct VNCPrefs * , LONG ) FUNCTION Load the preferences of a given ViNCEd window to a prefs buffer, allocated by AllocPrefsBuffer(). INPUTS cn - A pointer to the ViNCEd main structure. Need not to be locked here. buffer - the VNCPrefs structure, allocated by AllocPrefsBuffer() and filled by you. size - must be set to -1 RESULTS zero for failure and non-zero for success. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. SEE ALSO SetWindowPrefs(), AllocPrefsBuffer(), vnc/Prefs.h vnc.library/AllocPrefsBuffer vnc.library/AllocPrefsBuffer NAME AllocPrefsBuffer - allocate a buffer for holding prefernces. SYNOPSIS prefs = AllocPrefsBuffer ( ) d0 struct VNCPrefs * AllocPrefsBuffer ( VOID ) FUNCTION Allocate a buffer capable of holding the ViNCEd preferences. INPUTS RESULTS a pointer to a initialized struct VNCPrefs. The factory default prefs will have been filled in already. Returns NULL in case no free storage is available. NOTES This function MUST be called to allocate a buffer for holding the preferences. The size of the preferences structure has changed many times in the past, and will continue to change. This call ensures that enough memory is allocated to hold a up-to-date version of the preferences. This structure, as allocated by this function, MUST be used by all preferences related functions. SEE ALSO FreePrefsBuffer(), vnc/Prefs.h vnc.library/FreePrefsBuffer vnc.library/FreePrefsBuffer NAME FreePrefsBuffer - deallocate preferences. SYNOPSIS FreePrefsBuffer ( prefs ) a1 VOID FreePrefsBuffer ( struct VNCPrefs * ) FUNCTION Deallocate a previously allocated preferences buffer of AllocPrefsBuffer(). INPUTS prefs - a pointer to the preferences buffer allocated by AllocPrefsBuffer(). It is save to pass in NULL. RESULTS NOTES This function MUST be called to release a preferences buffer allocated by AllocVNCPrefs(). There's no other documented way of deleting this buffer. SEE ALSO AllocPrefsBuffer(), vnc/Prefs.h vnc.library/List2Prefs vnc.library/List2Prefs NAME List2Prefs - build preferences strings from list SYNOPSIS ok = List2Prefs ( cn , mlist , blist , prefs , mlen , blen d0 a5 a0 a2 a1 d0 d2 ,mnum , bnum) d1 d2 LONG List2Prefs ( struct ViNCWindow * , struct List * , struct List * , struct VNCPrefs * , UWORD , UWORD , UWORD , UWORD ) ok = List2Prefs_CN ( mlist , blist , prefs , mlen , blen d0 a0 a2 a1 d0 d2 ,mnum , bnum) d1 d2 LONG List2Prefs_CN ( struct List * , struct List * , struct VNCPrefs * , UWORD , UWORD , UWORD , UWORD ) FUNCTION Given two lists consisting of struct ViNCMacro *'s and struct ViNCButton *'s, this function fills in the macro and button settings into the preferences structure. INPUTS cn - a pointer to a struct ViNCWindow. MUST be locked with LockWindow() before calling this function. mlist - an exec style doubly linked list, filled with struct ViNCMacros *. blist - an exec style doubly linked list, filled with struct ViNCButtons *. prefs - a pointer to the preferences buffer allocated by AllocPrefsBuffer(). mlen - the maximal length of a macro, should be set to VPF_FUNCLENGTH. blen - the maximal length of a button title, should be set to VPF_SHORTLENGTH. mnum - the maximal number of macros to be filled in, should be set to VPF_MACROS. bnum - the maximal number of buttons to be filled in, should be set to VPF_MAXBUTTONS. RESULTS zero for failure or non-zero for success. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. The encoding of the strings in the preferences is somewhat un- convenient for the C author. To avoid this drawback, the list of macros and buttons can be converted to a linked list of structures containing the same information which is much easier to handle - this is done by Prefs2List(). This function reverses this process and fills in the lists back to the preferences structure. After you're done with the lists, call FreeMacroList() to get rid of them. The system macros and some system texts count also as "macros"! VPF_MACROS is therefore LARGER than ten, the number of user macros. SEE ALSO Prefs2List(), FreeMacroList(), vnc/Prefs.h, exec/lists.h vnc.library/Prefs2List vnc.library/Prefs2List NAME Prefs2List - build list of preferences strings SYNOPSIS ok = Prefs2List ( cn , mlist , blist , prefs , mlen , blen d0 a5 a0 a2 a1 d0 d2 ,mnum , bnum) d1 d2 LONG Prefs2List ( struct ViNCWindow * , struct List * , struct List * , struct VNCPrefs * , UWORD , UWORD , UWORD , UWORD ) ok = Prefs2List_CN ( mlist , blist , prefs , mlen , blen d0 a0 a2 a1 d0 d2 ,mnum , bnum) d1 d2 LONG Prefs2List_CN ( struct List * , struct List * , struct VNCPrefs * , UWORD , UWORD , UWORD , UWORD ) FUNCTION Given a ViNCEd preferences structure, this function builds two lists of the macros and buttons defined in the preferences structure for easier access. INPUTS cn - a pointer to a struct ViNCWindow. MUST be locked with LockWindow() before calling this function. mlist - an exec style doubly linked list. This list is filled in with struct ViNCMacros *'s. blist - an exec style doubly linked list. This list will be filled with struct ViNCButtons *. prefs - a pointer to the preferences buffer allocated by AllocPrefsBuffer(). mlen - the maximal length of a macro, should be set to VPF_FUNCLENGTH. The vnc.library will allocate enough space for the structures to hold strings of at least this size. blen - the maximal length of a button title, should be set to VPF_SHORTLENGTH. The vnc.library will allocate at least "mlen" bytes for the button body, and "blen" bytes for the button title. mnum - the maximal number of macros to be filled in, should be set to VPF_MACROS. bnum - the maximal number of buttons to be filled in, should be set to VPF_MAXBUTTONS. RESULTS zero for failure or non-zero for success. In case of failure, both lists will be empty and all partially allocated structures will have been deallocated already. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. The encoding of the strings in the preferences is somewhat un- convenient for the C author. To avoid this drawback, the list of macros and buttons can be converted to a linked list of structures containing the same information which is much easier to handle, as done by Prefs2List(). You're now holding struct ViNCButtons and struct ViNCMacros that can be manipulated much easier. The strings associated to these structures will be at least the specified number of bytes long, even though the actual texts might be shorter. To copy these lists back to the preferences after modification, use List2Prefs(). To After you're done with the lists, call FreeMacroList() to get rid of them. SEE ALSO List2Prefs(), FreeMacroList(), vnc/Prefs.h, exec/lists.h vnc.library/FreeMacroList vnc.library/FreeMacroList NAME FreeMacroList - deallocate a list build by Prefs2List SYNOPSIS FreeMacroList ( cn , list ) a5 a0 VOID FreeMacroList ( struct ViNCWindow * , struct List * ) FreeMacroList_CN ( list ) a0 VOID FreeMacroList_CN ( struct List * ) FUNCTION This function deallocates a list build by Prefs2List(). Both lists, the macro list as well as the button list should be passed in to release them. INPUTS cn - a pointer to a struct ViNCWindow. MUST be locked with LockWindow() before calling this function. list - an exec style doubly linked list, filled either with struct ViNCMacros or struct ViNCButtons. RESULTS NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. This function MUST be called to release the lists allocated with Prefs2List. Both lists, the macro list and the button list must be passed to this function to get deallocated. It is safe to pass an empty (but initialized!) list. SEE ALSO List2Prefs(), Prefs2List(), vnc/Prefs.h, exec/lists.h vnc.library/SendRequestPattern vnc.library/SendRequestPattern NAME SendRequestPattern - expand a search pattern by a requester SYNOPSIS ok = SendRequestPattern ( cn , pat ) d0 a5 a0 BOOL SendRequestPattern ( struct ViNCWindow * , char * ) ok = SendRequestPattern_CN ( pat ) d0 a0 BOOL SendRequestPattern_CN ( char * ) FUNCTION Sends an asynchronous request to the TAB supervisor to expand a given pattern. If the user satisfies the request, the pattern will be inserted back in the ViNCEd window. INPUTS cn - a pointer to a struct ViNCWindow. MUST be locked with LockWindow() before calling this function. pat - a standard dos match pattern. RESULTS a boolean success/failure indicator. This indicator does ONLY inform you whether the request was successfully sent to the supervisor. It DOES NOT include that the request was satisfied by the user, or whether there was a failure in the supervisor code itself. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. You usually DO NOT want to call this function. It is provided to allow an alternative macro expansion to hook in here. It is, however, called by the library itself in case a macro with a pattern has to be expanded. BUGS The string passed in MUST stay valid as long as the expansion is still working. This is usually not a problem since you don't want to call this routine anyways; instead, you might want to patch it. SEE ALSO LockWindow(), ConvertString() vnc.library/SendWindowOpens vnc.library/SendWindowOpens NAME SendWindowOpens - inform the TAB expansion about opening the window SYNOPSIS ok = SendWindowOpens ( cn ) d0 a5 BOOL SendWindowOpens ( struct ViNCWindow * ) ok = SendWindowOpens_CN ( ) d0 BOOL SendWindowOpens_CN ( VOID ) FUNCTION Send a request to the TAB expansion supervisor that the intuition window associated to a WiNCEd window was opened. This request is used to install the icon drop feature. INPUTS cn - a pointer to a struct ViNCWindow. MUST be locked with LockWindow() before calling this function. RESULTS a boolean success/failure indicator. This procedure is actually synchronous. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. You usually DO NOT want to call this function. It is provided to allow an alternative TAB expansion to hook in here. It is, however, called by the library itself in case the intuition window opens to allow installing the icon drop feature, etc. BUGS The name is misleading. This is a synchronous request. This function calls the workbench library function AddAppWindowA() directly from the handler task. While not a problem on a standard Amiga system, I can think of some patches where this leads to a problem. However, I currently don't see another way of doing this. SEE ALSO SendWindowCloses(), SendWindowQuits(), AddAppWindowA() vnc.library/SendWindowCloses vnc.library/SendWindowCloses NAME SendWindowCloses - inform the TAB expansion about closing the window SYNOPSIS ok = SendWindowCloses ( cn ) d0 a5 BOOL SendWindowCloses ( struct ViNCWindow * ) ok = SendWindowCloses_CN ( ) d0 BOOL SendWindowCloses_CN ( VOID ) FUNCTION Send a request to the TAB expansion supervisor that the intuition window associated to a WiNCEd window is about to be closed. This request is used to remove the icon drop feature. INPUTS cn - a pointer to a struct ViNCWindow. MUST be locked with LockWindow() before calling this function. RESULTS a boolean success/failure indicator. This is actually a synchronous request. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. You usually DO NOT want to call this function. It is provided to allow an alternative TAB expansion to hook in here. It is, however, called by the library itself in case the intuition window closes to allow removing the icon drop feature, etc. BUGS The name is misleading. This is a synchronous request. This function calls the workbench library function RemoveAppWindow() directly from the handler task. While not a problem on a standard Amiga system, I can think of some patches where this leads to a problem. However, I currently don't see another way of doing this. SEE ALSO SendWindowOpens(), SendWindowQuits(), RemoveAppWindow() vnc.library/SendWindowQuit vnc.library/SendWindowQuits NAME SendWindowQuits - inform the TAB expansion to shut down. SYNOPSIS ok = SendWindowQuits ( cn ) d0 a5 BOOL SendWindowQuits ( struct ViNCWindow * ) ok = SendWindowQuits_CN ( ) d0 BOOL SendWindowQuits_CN ( VOID ) FUNCTION Send a request to the TAB expansion supervisor that the handler is about to shut down. This is a bit more radical than the SwitchTabExpansion() call. The handler is also supposed to remove a possible icon drop feature, as well as to shut down completely, whereas it is possible to disable the TAB expansion temporarely with SwitchTabExpansion(). INPUTS cn - a pointer to a struct ViNCWindow. MUST be locked with LockWindow() before calling this function. RESULTS a boolean success/failure indicator. This is an assynchronous request, the indicator does only tell you whether the routine was able to deliver the request to the TAB expansion task, NOT MORE. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. You usually DO NOT want to call this function. It is provided to allow an alternative TAB expansion to hook in here. It is, however, called by the library itself in case the handler shuts down. The handler shut, upon arrival of this message, remove the icon drop, and shutdown itself. BUGS This function calls the workbench library function RemoveAppWindow() directly from the handler task. While not a problem on a standard Amiga system, I can think of some patches where this leads to a problem. However, I currently don't see another way of doing this. Feel prepared that this routine is called MORE THAN ONCE. This might happen if the handler wasn't able to shut down in time. The details about this routine are rather messy; since this HAS TO BE asynchronous to avoid deadlocks, but on the other hand the handler task has to know when the expansion has, indeed, shut down, this problem is solved by a trick: The TAB expansion task opens a ViNCEd stream itself which will inhibit that the handler shuts down before the TAB expansion quits. On this request, the handler shuts down and, while doing so, closes this stream. If the ACTION_CLOSE packet is received by the handler, this function is called again. Furthermore, to allow the close window requester working, the open count of the ViNCWindow is incremented and decremented manually by this function, which is usually a bad thing(tm) to do. Unless you know quite a lot about these internals, it's probably not a good idea to hook in here. SEE ALSO SendWindowOpens(), SendWindowCloses(), RemoveAppWindow() vnc.library/VNCRequestFile vnc.library/VNCRequestFile NAME VNCRequestFile - display a file requester SYNOPSIS ok = VNCRequestFile ( cn , request ) d0 a5 a0 LONG VNCRequestFile ( struct ViNCWindow * , struct ViRequest * ) ok = VNCRequestFile_CN ( request ) d0 a0 LONG VNCRequestFile_CN ( struct ViRequest * ) FUNCTION Display a file requester described by the structure ViRequest, and fill in the requested file and directory names. INPUTS cn - a pointer to a struct ViNCWindow. Need not to be locked. request - a pointer to an initialized struct ViRequest: struct ViRequest { char *vreq_Hail; /* title string */ char *vreq_File; /* file name */ char *vreq_Dir; /* directory name */ struct Window *vreq_Window; /* window to lock */ UWORD vreq_Flags; /* flags, see below */ ULONG vreq_reserved; /* must be zero */ char *vreq_Pattern; /* pattern matching string */ WORD vreq_LeftEdge; WORD vreq_TopEdge; /* requester position */ UWORD vreq_Width; UWORD vreq_Height; /* requester dimensions */ }; The following flags can be set: /* Split file name in file and directory, fill in dir automatically */ #define VREQ_AUTOSPLIT_BIT 0 #define VREQ_AUTOSPLIT_MASK (1L<<0) /* Split file in dir and pattern, clear file */ #define VREQ_AUTOPAT_BIT 1 #define VREQ_AUTOPAT_MASK (1L<<1) /* Join file and dir after requesting */ #define VREQ_AUTOJOIN_BIT 2 #define VREQ_AUTOJOIN_MASK (1L<<2) /* Requester dimensions are valid */ #define VREQ_DIMENSIONS_BIT 8 #define VREQ_DIMENSIONS_MASK (1L<<8) RESULTS a boolean success/failure indicator. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. Depending on what is available, this function uses either the arp.library or the asl.library. If ReqChange is installed, the asl call will be redirected to reqtools. However, it is likely that support for the arp.library is about to be removed in the 3.70 release of ViNCEd. BUGS I really don't remember what the ViNCWindow pointer is used for in this routine, however, passing in NULL is NOT allowed. A future release should really work without it. SEE ALSO vnc/requester.h vnc.library/CtrlZSuspend vnc.library/CtrlZSuspend NAME CtrlZSuspend - suspend the given owner, launch/find a new shell SYNOPSIS ok = CtrlZSuspend ( cn , owner ) d0 a5 a4 LONG CtrlZSuspend ( struct ViNCWindow * , struct ViOwner * ) ok = CtrlZSuspend_CN ( owner ) d0 a4 LONG CtrlZSuspend_CN ( struct ViOwner * ) FUNCTION Suspend the process(es) associated to the supplied owner. Find a new free shell process or generate a new shell process, bring this process to foreground. INPUTS cn - a pointer to a struct ViNCWindow. MUST be locked with LockWindow(). owner - a pointer to a ViNCEd owner structure, see vnc/owner.h RESULTS a boolean success/failure indicator. This this packet sends basically a request to the TAB expansion supervisor, this indicates only whether the function was able to send the request, not if it was able to launch a new shell. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. You usually DO NOT want to call this function. It is provided to allow an alternative TAB expansion to hook in here. It is, however, called by the library itself in case the user presses ^Z to suspend the foreground owner. Some sanity checks have already been made by the library if this function is called, but not enough. Since the ^Z feature is more or less a hack, you should check very carefully if the process of the owner can be aborted safely. Especially, the current implementation checks - ViNCEd is in shell mode - the TAB expansion supervisor is up and running - whether another suspend request is still running - the port of the last process of this owner that wrote to the ViNCEd window is still available. - whether any other I/O requests are pending. - whether this port is a valid port operating on signal basis - whether the task of this port is associated to a valid and known task in the exec list of tasks. - whether a CLI for this task is available. - whether a module is loaded for this CLI or it is non-interactive. - whether it is indeed in foreground If all this is fine, the task is temporarely removed from execution. It is the job of the TAB expansion supervisor to resceldure this task and to run a new shell. BUGS The ^Z feature is really messy, but I don't see a cleaner way of making this possible with the current shell. The ViNCEd 3.60 version implements the "Medium Mode" with which something like this should be able much more system friendly. Unfortunately, there is not yet a shell that supports it. SEE ALSO vnc/owner.h, dos/dosextens.h, exec/tasks.h, exec/ports.h vnc.library/VNCUniqueID vnc.library/VNCUniqueID NAME VNCUniqueID - provide a unique ID SYNOPSIS ok = VNCUniqueID ( ) ULONG VNCUniqueID ( VOID ) FUNCTION Build a new unique ID. This function should be used in case you need a unique name for a new owner. INPUTS RESULTS a system wide unique unsigned long number. Won't be returned a second time unless this routine runs out of new available IDs. NOTES If the utility library is available, this function is identical to UniqueID(); hence, the number returned is even unique in a system wide context. If the utility library is not availabe, i.e. in a 1.3 environment, the vnc.library implements its own version. However, it is likely that support for 1.2 and 1.3 will be dropped in release 3.70 of ViNCEd. SEE ALSO UniqueID() vnc.library/GetNodeN vnc.library/GetNodeN NAME GetNodeN - get the nth node of a list. SYNOPSIS node = GetNodeN ( list , count ) d0 a0 d0 struct Node * GetNodeN ( struct List * , ULONG count ) FUNCTION Find the node of a given index in a list. INPUTS list - the list to search the node in. count - the index of the node to locate. The first node in the list is node number #0. RESULTS the node number n, or NULL if the list run out of nodes. NOTES SEE ALSO vnc.library/AllocEdMem vnc.library/AllocEdMem NAME AllocEdMem - allocate static memory in ViNCEd context SYNOPSIS mem = AllocEdMem ( cn , bytesize , reqments ) d0 a5 d0 d1 void * AllocEdMem ( struct ViNCWindow * , ULONG , ULONG ) mem = AllocEdMem_CN ( bytesize , reqments ) d0 d0 d1 void * AllocEdMem_CN ( ULONG , ULONG ) FUNCTION Allocate memory in context of the ViNCEd window. This memory allocation is pooled; the memory allocated this way will be deallocated automatically as soon as the ViNCEd window, i.e. the handler task shuts down. The memory allocated by this function is static memory, as all system memory; i.e. the memory allocated will not move. INPUTS cn - the ViNCWindow structure to take the memory from. MUST be locked before calling this function. bytesize - number of bytes to allocate reqments - requirements. Only MEMF_PUBLIC requests will be pooled, but all requests will be satisfied if possible. RESULTS a pointer to the memory allocated, or NULL on failure. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. SEE ALSO AllocMem(), FreeEdMem(), exec/memory.h vnc.library/FreeEdMem vnc.library/FreeEdMem NAME FreeEdMem - deallocate editor memory. SYNOPSIS FreeEdMem ( cn , mem ) a5 a1 VOID FreeEdMem ( struct ViNCWindow * , void * ) FreeEdMem_CN ( mem ) a1 VOID FreeEdMem_CN ( void * ) FUNCTION Deallocate memory in context of the ViNCEd window. You should give back all memory allocated by AllocEdMem, even though this is done by ViNCEd automatically as soon as the handler shuts down. INPUTS cn - the ViNCWindow structure to take the memory from. MUST be locked before calling this function. mem - pointer of the memory block to release. It is safe to pass in NULL. RESULTS NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. SEE ALSO AllocEdMem(), FreeMem(), exec/memory.h vnc.library/AllocLine vnc.library/AllocLine NAME AllocLine - allocate dynamic memory. SYNOPSIS dynnode = AllocLine ( cn , size ) d0 a5 d0 struct DynNode * AllocLine ( struct ViNCWindow * , UWORD ) dynnode = AllocLine_CN ( size ) d0 d0 struct DynNode * AllocLine_CN ( UWORD ) FUNCTION Allocate dynamic memory in the editor window context. INPUTS cn - the ViNCWindow structure to take the memory from. MUST be locked before calling this function. size - size of memory to allocate. This size does not include the DynNode header, as well as the LineBody/OutNodeBody. The sizes of these structures are added automatically to the requested size. RESULTS A pointer to a struct DynOutNode or DynLine, with a struct DynNode header. Should be casted to the apropriate type and initialized as such type. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. This is dynamic memory, be warned! This means that the memory allocated by this call MAY MOVE thru memory if the vnc.library runs out of free space. DO NOT hold pointers to these structures, they may get invalid as soon as anybody else (or you yourself) allocate memory thru AllocLine(). Instead, insert the LineBody/ OutnodeBody part of this structure in any exec list you want. The list pointers will be then corrected automagically by the vnc.library as soon as this memory must be relocated. It is VERY important that you set the vln_succln/vln_predln pointers in the "...body" structure to NULL as soon as you remove this structure from a list. Do NOT leave in "dangling pointers" or you'll experience a surprise if this structure must be relocated. Another safe way of keeping a pointer on this structure is to use the UserLinePtr in the UserNode of the ViNCWindow structure, but you must make sure that you're the only user of this pointer. This pointer will be corrected by the vnc.library, too. Remember to set this poiner to NULL as soon as you don't need it any longer. It's usually not a good idea to play with dynamical memory unless you know what you're doing. SEE ALSO FreeLine(), vnc/dynamics.h vnc.library/FreeLine vnc.library/FreeLine NAME FreeLine - release dynamic memory. SYNOPSIS FreeLine ( cn , line ) a5 a0 VOID FreeLine ( struct ViNCWindow * , struct DynNode * ) FreeLine_CN ( line ) a0 VOID FreeLine_CN ( struct DynNode * ) FUNCTION Release dynamical memory. INPUTS cn - the ViNCWindow structure the memory was taken from. MUST be locked before calling this function. line - pointer to the struct DynNode, as allocated by the AllocLine() call. RESULTS NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. This is dynamic memory, be warned! This means that the memory allocated by this call MAY MOVE thru memory if the vnc.library runs out of free space. DO NOT hold pointers to these structures, they may get invalid as soon as anybody else (or you yourself) allocate memory thru AllocLine(). Instead, insert the LineBody/ OutnodeBody part of this structure in any exec list you want. The list pointers will be then corrected automagically by the vnc.library as soon as this memory must be relocated. It is VERY important that you set the vln_succln/vln_predln pointers in the "...body" structure to NULL as soon as you remove this structure from a list. Do NOT leave in "dangling pointers" or you'll experience a surprise if this structure must be relocated. Make sure the vln_succln/vln_predln pointers in the "...body" structure are set both to NULL if you call this function, or ViNCEd will try to remove this structure from a doubly linked list, whether it is inserted there or not. It's usually not a good idea to play with dynamical memory unless you know what you're doing. SEE ALSO AllocLine(), vnc/dynamics.h vnc.library/NotifyChOwner vnc.library/NotifyChOwner NAME NotifyChOwner - notify an Owner about a fg/bg change. SYNOPSIS ok = NotifyChOwner ( cn , old , new , cmd ) d0 a5 a0 a1 d0 BOOL NotifyChOwner ( struct ViNCWindow * , struct ViOwner * , struct ViOwner * , char cmd ) ok = NotifyChOwner_CN ( old , new , cmd ) d0 a0 a1 d0 BOOL NotifyChOwner_CN ( struct ViOwner * , struct ViOwner * , char cmd ) FUNCTION Notifies the shell or other programs about the change of the foreground / background context. Prints an informative prompt for the user in the form of a prompt. INPUTS cn - the ViNCWindow structure. MUST be locked before calling this function. old - the old foreground owner, might be NULL. new - the new owner which is about to be brought to foreground. cmd - a command character what to do with the information. Currently defined are: 'C' change the foreground/background context 'S' set the foreground owner, old is NULL RESULTS a boolean success/failure indicator. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. You usually DO NOT want to call this function. It is provided to allow an alternative Job control to hook in here. It is, however, called by the library itself in case the foreground/background owner changes. What this procedure does is that it prints a tiny prompt, consisting of the name of program brought to front in case a module is loaded in the shell reactivated, or it just "remote types" RETURN in case no module is active. This should result in redisplaying the prompt for the shell brought to foreground. This routine includes also some sanety checks whether the process is really ready to be brought to foreground. BUGS The job control is somehow a hack since the original Amiga shell does not support such a thing. ViNCEd supports a cleaner solution in the form of the "medium console mode", but there is unfortunately not yet a shell that makes use of it. SEE ALSO NotifyClearScreen(), LockWindow() vnc.library/NotifyClearScreen vnc.library/NotifyClearScreen NAME NotifyClearScreen - notify an owner about redisplaying its prompt SYNOPSIS ok = NotifyClearScreen ( cn ) d0 a5 BOOL NotifyClearScreen ( struct ViNCWindow * ) ok = NotifyClearScreen_CN ( ) d0 BOOL NotifyClearScreen_CN ( VOID ) FUNCTION Notifies the current foreground owner that the screen has been cleared and it should redraw its window contents. INPUTS cn - the ViNCWindow structure to take the memory from. MUST be locked before calling this function. RESULTS a boolean success/failure indicator. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. You usually DO NOT want to call this function. It is provided to allow an alternative Job control to hook in here. It is, however, called by the library itself in case the user clears the screen and the foreground owner should redraw its window contents. The current implementation checks whether a shell is the active foreground owner and simulates a RETURN keypress to redisplay the prompt. BUGS The job control is somehow a hack since the original Amiga shell does not support such a thing. ViNCEd supports a cleaner solution in the form of the "medium console mode", but there is unfortunately not yet a shell that makes use of it. There should be really an owner paramter for this routine, but there isn't. The routine has to use the ActualOwner field from the ViNCWindow structure to find out which owner to send this message to. SEE ALSO NotifyChOwner(), LockWindow() vnc.library/VNCAToI vnc.library/VNCAToI NAME VNCAToI - convert an ASCII encoded decimal number to integer SYNOPSIS number = VNCAToI ( convert ) d0 a0 LONG VNCAToI ( struct Convert * ) FUNCTION takes a simple structure containing a character pointer and tries to convert the ASCII encoded decimal number into its binary representation. Returns the number read from the provided buffer, and a sucess/failure indicator as well as the pointer to the first character unable to convert back in the structure. INPUTS convert - a pointer to the following structure: struct Convert { char *cv_input; /* input string */ ULONG cv_success; /* succes/failure indicator filled in by this routine */ } RESULTS the number converted. A pointer to the first character unable to convert in cv_input, and a boolean success/failure indicator in cv_success. The number is only valid if cv_success is non-zero. Assembly language programmers will receive cv_input in the register a0 and cv_success in the register d1. NOTES This function changes automatically the number base if special characters in the string say so. A leading '$' or '0x' identifies the number as hexadecimal, 'o', 'O' or '§' identifies octal numbers, '%' is binary and '#' is decimal. This routine supports integers up to +/- 2^32. SEE ALSO VNCHToI(), VNCStrToL() vnc.library/VNCHToI vnc.library/VNCHToI NAME VNCHToI - convert an ASCII encoded hex number to integer SYNOPSIS number = VNCHToI ( convert ) d0 a0 LONG VNCHToI ( struct Convert * ) FUNCTION takes a simple structure containing a character pointer and tries to convert the ASCII encoded hexadecimal number into its binary representation. Returns the number read from the provided buffer, and a sucess/failure indicator as well as the pointer to the first character unable to convert back in the structure. INPUTS convert - a pointer to the following structure: struct Convert { char *cv_input; /* input string */ ULONG cv_success; /* succes/failure indicator filled in by this routine */ } RESULTS the number converted. A pointer to the first character unable to convert in cv_input, and a boolean success/failure indicator in cv_success. The number is only valid if cv_success is non-zero. Assembly language programmers will receive cv_input in the register a0 and cv_success in the register d1. NOTES This function changes automatically the number base if special characters in the string say so. A leading '$' or '0x' identifies the number as hexadecimal, 'o', 'O' or '§' identifies octal numbers, '%' is binary and '#' is decimal. This routine supports integers up to +/- 2^32. SEE ALSO VNCAToI(), VNCStrToL() vnc.library/VNCStrToL vnc.library/VNCStrToL NAME VNCStrToL - convert an ASCII encoded number to integer SYNOPSIS number = VNCStrToL ( convert , base ) d0 a0 d0 LONG VNCStrToL ( struct Convert * , ULONG base ) FUNCTION takes a simple structure containing a character pointer and tries to convert the ASCII encoded number into its binary representation. Returns the number read from the provided buffer, and a sucess/failure indicator as well as the pointer to the first character unable to convert back in the structure. INPUTS convert - a pointer to the following structure: struct Convert { char *cv_input; /* input string */ ULONG cv_success; /* succes/failure indicator filled in by this routine */ } base - the number base to use. Only accepted values are 2, 8, 10 and 16. RESULTS the number converted. A pointer to the first character unable to convert in cv_input, and a boolean success/failure indicator in cv_success. The number is only valid if cv_success is non-zero. Assembly language programmers will receive cv_input in the register a0 and cv_success in the register d1. NOTES This function changes automatically the number base if special characters in the string say so. A leading '$' or '0x' identifies the number as hexadecimal, 'o', 'O' or '§' identifies octal numbers, '%' is binary and '#' is decimal. This routine supports integers up to +/- 2^32. SEE ALSO VNCAToI(), VNCHToI() vnc.library/VNCIToA vnc.library/VNCIToA NAME VNCIToA - convert an integer to a decimal ASCII representation SYNOPSIS VNCIToA( number , buffer ) d0 a0 VOID VNCIToA ( LONG , char * ) FUNCTION takes a binary encoded integer number and converts it to a decimal ASCII representation in the buffer. INPUTS number - the number to convert. buffer - a pointer to the buffer the number should be converted to. Must be at least 12 bytes long to hold even extreme cases. RESULTS NOTES This function is signed, i.e. a minus sign will be put in front of negative numbers. This routine supports integers up to +/- 2^32. SEE ALSO VNCSPrintf() vnc.library/VNCSPrintf vnc.library/VNCSprintF NAME VNCSPrintf - print formatted into a string SYNOPSIS VNCSPrintf ( buffer , stream , format ) a0 a1 a2 VOID VNCSPrintf ( char * , char * , char * ) FUNCTION prints characters into the string "buffer", using formatting information from formatstring and data from stream. INPUTS buffer - the buffer to place the output in. No range checking is performed. stream - the input stream to take the numbers from. This is a pointer to an "array" type structure. format - a C style format string RESULTS NOTES This function uses the RawDoFmt() routine of the exec library to format its output. This means especially that %d and %c are word sized. Use the modifier "l" to make strings long sized. This might result in wierd-looking formatting information as %lc for characters if, for your compiler, int = long int. SEE ALSO VNCIToA(), RawDoFmt() vnc.library/VNCStrCmp vnc.library/VNCStrCmp NAME VNCStrCmp - compare strings case insensitive SYNOPSIS result = VNCStrCmp ( str1 , str2 ) d0 a0 a1 LONG VNCStrCmp ( char * , char * ) FUNCTION compares the two string arguments. If the stings have different length but are otherwise identical, the shorter string is "smaller". INPUTS str1, str2 - the strigs to be compared RESULTS <0 if str1 < str2, =0 if str1 = str2 and >0 if str1 > str2. NOTES this function is identical to the Stricmp() routine of the utility library if this is available. It is therefore localized if the locale library is available, too. If the utility library is NOT available, ViNCEd uses its own function; however, this happens only in Os versios 1.2 and 1.3 and it is likely that this support will be removed in the release 3.70 of ViNCEd. SEE ALSO Stricmp(), VNCStrICmp() vnc.library/VNCStrICmp vnc.library/VNCStrICmp NAME VNCStrCmp - compare strings case insensitive, length limited SYNOPSIS result = VNCStrICmp ( str1 , str2 , max ) d0 a0 a1 d0 LONG VNCStrICmp ( char * , char * , ULONG ) FUNCTION compares the two string arguments, up to max characters. If the stings have different length but are otherwise identical, the shorter string is "smaller". INPUTS str1, str2 - the strigs to be compared max - the maximal number of characters to be compared RESULTS <0 if str1 < str2, =0 if str1 = str2 and >0 if str1 > str2. NOTES this function is identical to the Strnicmp() routine of the utility library if this is available. It is therefore localized if the locale library is available, too. If the utility library is NOT available, ViNCEd uses its own function; however, this happens only in Os versios 1.2 and 1.3 and it is likely that this support will be removed in the release 3.70 of ViNCEd. BUGS this function should have been called VNCStrNCmp(). SEE ALSO Strnicmp(), VNCStrCmp() vnc.library/VNCToUpper vnc.library/VNCToUpper NAME VNCToUpper - convert a character to upper case. SYNOPSIS result = VNCToUpper ( ch ) d0 d0 char VNCToUpper ( char ) FUNCTION Converts the character passed in to upper case, using the locale database if available. INPUTS ch - the character to be set to upper case. RESULTS the character in upper case. NOTES this function is identical to the ToUpper() routine of the utility library if this is available. It is therefore localized if the locale library is available, too. If the utility library is NOT available, ViNCEd uses its own function; however, this happens only in Os versios 1.2 and 1.3 and it is likely that this support will be removed in the release 3.70 of ViNCEd. SEE ALSO ToUpper() vnc.library/ConvertWindowTitle vnc.library/ConvertWindowTitle NAME ConvertWindowTitle - expand ctrl types in a window title SYNOPSIS ConvertWindowTitle ( cn , owner , from , to ) VOID ConvertWindowTitle ( struct ViNCWindow * , struct ViOwner * , char * , char * ) ConvertWindowTitle_CN ( owner , from , to ) VOID ConvertWindowTitle_CN ( struct ViOwner * , char * , char * ) FUNCTION takes a window title like string with control sequences such as %n, %r or %s and expands these strings according to the information found in the owner structure. INPUTS cn - a pointer to the ViNCWindow main structure. MUST be locked with LockWindow() owner - a pointer to a struct ViOwner providing the process information from - source string to - destination string, must be 256 bytes large RESULTS NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. You usually DO NOT want to call this function. It is provided to allow an alternative window title expansion. It is, however, called by the library itself in case the window title must be refreshed. A hooked in replacement routine MUST truncate the output string to 256 characters (including the NUL character at the end) to avoid overrunning buffers. The output buffer is documented to be 256 characters large. The current implementation reads the strings to be expanded from the process in the owner structure, including some sanety checks to make sure the process is stable. This is somehow a hack. A future version might provide a safer method. It should be actually the matter of the shell to set the window title thru an ESC sequence - which is possible for ViNCEd - but it doesn't do this. SEE ALSO LockWindow(), the ViNCEd guide vnc.library/FindCloseMacro vnc.library/FindCloseMacro NAME FindCloseMacro - provide the proper macro to shutdown a program SYNOPSIS macro = FindCloseMacro ( cn , owner ) d0 a5 a4 char * FindCloseMacro ( struct ViNCWindow * , struct ViOwner * ) macro = FindCloseMacro_CN ( owner ) d0 a4 char * FindCloseMacro_CN ( struct ViOwner * ) FUNCTION Reads the information from the owner structure and decides, whether a shell is running or another program is active. Selects the proper macro from the ViNCEd macro list and returns the macro body to be expanded. INPUTS cn - a ViNCEd window main structure, MUST be locked with LockWindow() owner - a pointer to the owner structure to be investigated RESULTS a character pointer to the macro body, or NULL if no macro is available for this function. In this case, an EOF should be generated to shutdown the stream. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. You usually DO NOT want to call this function. It is provided to allow an alternative job control to hook in. It is, however, called by the library itself in case the user pressed the close gadget of the window or wants to shutdown the stream otherwise. A replacement routine must make some sanity checks on the owner structure to make sure that the process investigated is valid and still active. It must return a shutdown string or NULL in case an EOF should be send to the owner in question. A future shell should always receive an EOF condition and send the required string to the program itself, manually. SEE ALSO LockWindow() vnc.library/PrintSuspend vnc.library/PrintSuspend NAME PrintSuspend - print a "job suspended message" SYNOPSIS PrintSuspend ( cn , port , owner ) a5 a0 a4 VOID PrintSuspend ( struct ViNCWindow * , struct MsgPort * , struct ViOwner * ) PrintSuspend_CN ( cn , port , owner ) a5 a0 a4 VOID PrintSuspend_CN ( struct ViNCWindow * , struct MsgPort * , struct ViOwner * ) FUNCTION Prints a " [...] suspended" message in case a suspended owner tries to print something to the screen. Requests a prompt from a running foreground shell. INPUTS cn - a pointer to the ViNCWindow structure, must be locked with LockWindow() first port - a pointer to the dos message port of the process which has been suspended owner - a pointer to the owner this process is part of RESULTS NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. You usually DO NOT want to call this function. It is provided to allow an alternative job control to hook in. It is, however, called by the library itself in case a job gets suspended and a suspend message has to be printed. This routine checks whether a shell or a program is active in this window, and prints the suspend message only if it's a shell. A press to RETURN is simulated in this case to request a shell prompt again. A replacement routine must make some sanity checks on the owner structure to make sure that the process investigated is valid and still active. A future shell should print this message itself. SEE ALSO LockWindow() vnc.library/QueueOwnerLine vnc.library/QueueOwnerLine NAME QueueOwnerLine - add inputs to a ViNCEd owner SYNOPSIS ok = QueueOwnerLine ( cn , owner , buffer , size ) d0 a5 a4 a0 d0 BOOL QueueOwnerLine ( struct ViNCWindow * , struct ViOwner , char * buffer, UWORD size ) ok = QueueOwnerLine_CN ( owner , buffer , size ) d0 a4 a0 d0 BOOL QueueOwnerLine_CN ( struct ViOwner , char * buffer, UWORD size ) FUNCTION This queues an input line into the output buffer of the given owner. The data will be not made visible on the screen. THIS IS A LOW-LEVEL FUNCTION. YOU DO NOT WANT TO CALL IT. USE THE DOS PACKET ACTION_QUEUE INSTEAD. The only reason to call this function from are replacement routines that patch into the ViNCEd job control functions and others. INPUTS cn - a pointer to the ViNCWindow main structure, MUST be locked with LockWindow(). owner - a pointer to the owner which should receive the data. buffer - the data to be placed into its input buffer. The buffer may be released afterwards or can be even kept on the stack. size - the size of the data. RESULTS a boolean success/failure code. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. DO NOT CALL THIS FUNCTION unless you patched into one of the ViNCEd job control etc. functions and MUST use this mechanism instead of sending a DOS packet. This function is identical to the ACTION_QUEUE dos packet, which should clearly be preferred. SEE ALSO LockWindow() vnc.library/PutLineData vnc.library/PutLineData NAME PutLineData - print data to the screen over an owner. SYNOPSIS size = PutLineData ( cn , owner , buffer , size ) d0 a5 a4 a0 d0 ULONG PutLineData ( struct ViNCWindow * , struct ViOwner , char * buffer, ULONG size ) ok = PutLineData_CN ( owner , buffer , size ) d0 a4 a0 d0 ULONG PutLineData_CN ( struct ViOwner , char * buffer, ULONG size ) FUNCTION This function prints out strings as if they have been written thru the dos function Write() - in fact, this is the low-level routine called if ViNCEd receivces an ACTION_WRITE, even though it is NOT called thru this interface. THIS IS A LOW-LEVEL FUNCTION. YOU DO NOT WANT TO CALL IT. USE THE DOS PACKET ACTION_WRITE INSTEAD. The only reason to call this function from are replacement routines that patch into the ViNCEd job control functions and others. INPUTS cn - a pointer to the ViNCWindow main structure, MUST be locked with LockWindow(). owner - a pointer to the owner which should receive the data. Must be given since some CSI sequences are owner specific. buffer - the data to be written; may contain all ViNCEd ESC/CSI sequences. size - the size of the data. RESULTS the number of characters written. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. DO NOT CALL THIS FUNCTION unless you patched into one of the ViNCEd job control etc. functions and MUST use this mechanism instead of sending a DOS packet. This function is identical to the ACTION_WRITE dos packet, which should clearly be preferred. SEE ALSO LockWindow() vnc.library/SendAsyncPacket vnc.library/SendAsyncPacket NAME SendAsyncPacket - send a ViNCEd packet asynchronously. SYNOPSIS ok = SendAsyncPacket ( file , type , arg1 , data , size ) d0 d1 d2 a1 a0 d0 LONG SendAsyncPacket ( BPTR , ULONG , void * , void * , ULONG ) FUNCTION Builds an async type packet and allocated memory for a buffer, copies the data into this buffer and sends the packet to ViNCEd. Returns immediately and does not wait for completion of the packet. INPUTS file - a BPTR to the file handle for communication type - the type of the packet to sent, e.g. ACTION_WRITE arg1 - the first argument to be placed into the arg1 parameter of the Packet structure. data - will be copied into a buffer and filled into the arg2 pointer of the packet. Since the data is copied, you may release the buffer immediately after calling this function size - the number of bytes in this buffer. Will be copied to arg3 of the packet. RESULTS DOSTRUE in case the packet could be delivered to ViNCEd. This DOES NOT mean that ViNCEd accepted this packet properly. DOSFALSE in case of failure. NOTES This is the asynchronous packet interface of ViNCEd. DO NOT try to roll your own async packets, use this one or AllocAsyncPacket() instead. This call is optimized to work for most packets requiring a buffer and a count, as ACTION_WRITE, ACTION_QUEUE, ACTION_PUSH, ACTION_SETLINE and others. Consult the ViNCEd guide for details. It is intrinsic to this method that you don't receive a success failure indicator for the packet send. ViNCEd will deallocate all buffers and the packet itself, and won't reply it at all. If a reply code is required, build a standard packet yourself and send to the owner port using PutMsg(), then continously call GetMsg() on your reply port for the return of this packet, as it works for all other handlers. You should, however, make sure that you send packets to the port in the file handle you received, i.e. filehandle -> fh_Type (NOT fh_Port, this is a bug in the dos.library documentation). DO NOT send packets to the port in the global DOS device list or to any other port. The proper port IS REQUIRED to identify the owner this packet comes from. SEE ALSO AllocAsyncPacket(), DoPkt(), VNCDoPacket(), dos/dosextens.h, the ViNCEd guide for the list of packets accepted. vnc.library/AllocAsyncPacket vnc.library/AllocAsyncPacket NAME AllocAsyncPacket - build a packet for asynchronous shipment SYNOPSIS stdpkt = AllocAsyncPacket ( file , size ) d0 d1 d0 struct StandardPacket * AllocAsyncPacket ( BPTR , ULONG ) FUNCTION Builds an async packet for asynchronous communication with ViNCEd. INPUTS file - a BPTR to the file handle for communication size - size of an additional data packet to be allocated with the packet. This does not include the size of the packet itself. RESULTS a struct StandardPacket or NULL in case of failure. NOTES This builds an asynchronous packet. If size is larger than zero, (stdkt + 1) points to a buffer for free use. Fill in all data as usual, BUT SET BIT 31 OF THE dp_type FIELD. This identifies an asynchronous packet. Then PutMsg() this packet to the owner port of ViNCEd and forget about it. ViNCEd will not reply it, and will deallocate the packet and the buffer after- wards. If a reply code is required, build a standard packet yourself and send to the owner port using PutMsg(), then continously call GetMsg() on your reply port for the return of this packet, as it works for all other handlers. You should, however, make sure that you send packets to the port in the file handle you received, i.e. filehandle -> fh_Type (NOT fh_Port, this is a bug in the dos.library documentation). DO NOT send packets to the port in the global DOS device list or to any other port. The proper port IS REQUIRED to identify the owner this packet comes from. SEE ALSO SendAsyncPacket(), DoPkt(), VNCDoPacket(), dos/dosextens.h, the ViNCEd guide for the list of packets accepted. vnc.library/VNCDoPacket vnc.library/VNCDoPacket NAME VNCDoPacket - send a dos packet synchronously. SYNOPSIS res1 = VNCDoPacket ( type , arg1 , arg2 , arg3 , arg4 , arg5 , d0 d0 d1 d2 d3 d4 d5 arg6 , arg7 , port ) d6 d7 a0 LONG VNCDoPacket ( LONG , LONG , LONG , LONG , LONG , LONG , LONG , LONG , struct MsgPort * ) FUNCTION Build and send a packet to a given message port, synchronously. RESULTS The primary result code of the packet. The secondary result code can be obtained by IoErr(). NOTES This call is almost identical to DoPkt() of the dos library except that a more useful register layout is available and, therefore, all packet parameters can be defined. This function is mainly here for pre 2.0 programs where no DoPkt() function of the dos.library was available. However, feel prepared that the Os 1.2/1.3 compatibility of ViNCEd will be removed in release 3.70 (even though this function will stay here). SEE ALSO SendAsyncPacket(), DoPkt() vnc.library/Foreground vnc.library/Foreground NAME Foreground - put the owner of a stream to foreground SYNOPSIS ok = Foreground ( flags , file ) d0 d0 d1 LONG Foreground ( ULONG , BPTR ) FUNCTION Sends the owner associated to the dos stream to foreground mode. Even though this is an asynchronous call, all packets send to ViNCEd after this call will reach the owner in foreground mode. INPUTS flags - flags for the call. Currently, no flags are defined and this MUST be set to zero. file - a file handle to a ViNCEd stream. RESULTS DOSTRUE if successful, DOSFALSE on failure. NOTES There is no guarantee that your owner will stay in foreground if this is called. This function should usually be called from a shell only, but the current AmigaDos shell doesn't support job control. SEE ALSO Background() vnc.library/Background vnc.library/Background NAME Background - put the owner of a stream to background SYNOPSIS ok = Background ( flags , file ) d0 d0 d1 LONG Background ( ULONG , BPTR ) FUNCTION Sends the owner associated to the dos stream to background mode. Even though this is an asynchronous call, all packets send to ViNCEd after this call will reach the owner in background mode. INPUTS flags - flags for the call. Since if the given owner is send to background, something else has to go to foreground. This is defined by the following flag: #define VINBF_SHELLONLY_BIT 0L #define VINBF_SHELLONLY_MASK (1<<0L) Send only waiting shells to foreground. If not set, all owners are considered. file - a file handle to a ViNCEd stream. RESULTS DOSTRUE if successful, DOSFALSE on failure. NOTES There is no guarantee that your owner will stay in background if this is called. This function should usually be called from a shell only, but the current AmigaDos shell doesn't support job control. SEE ALSO Foreground() vnc.library/ConvertString vnc.library/ConvertString NAME ConvertString - expand a macro body completely SYNOPSIS ok = ConvertString ( cn , from , to ) d0 a5 a0 a1 BOOL ConvertString ( struct ViNCWindow * , char * , char * ) ok = ConvertString_CN ( from , to ) d0 a0 a1 BOOL ConvertString_CN ( char * , char * ) FUNCTION Expands all backslash and bracket sequences in a macro body to a full string. INPUTS cn - a struct ViNCWindow pointer to the main window this macro came from. Need not to be locked with LockWindow(). from - source string. to - destination string. MUST be 256 characters large. RESULTS a boolean success/failure indicator. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. You usually DO NOT want to call this function. It is provided to allow an alternative macro expansion to hook in. It is, however, called by the library itself in case a macro body must be expanded. This function has a somewhat different job than SendRequestPattern(). This routine has to do the actual conversion, whereas SendRequestPattern() has to deliver a request to an external task for conversion. ViNCEd will call this function directly in case the macro body has no special characters in it, or will pass it to an external host with SendRequestPattern() in case it can't do the job alone, for example if a file requester has to be build. SEE ALSO SendRequestPattern() vnc.library/PoolCreateExtIO vnc.library/PoolCreateExtIO NAME PoolCreateExtIO - build an IORequest from the editor memory pool SYNOPSIS io = PoolCreateExtIO ( cn , port , size ) d0 a5 a1 d0 struct IORequest * PoolCreateExtIO ( struct ViNCWindow * , struct MsgPort * , UWORD size ) io = PoolCreateExtIO_CN ( port , size ) d0 a1 d0 struct IORequest * PoolCreateExtIO_CN ( struct MsgPort * , UWORD size ) FUNCTION Build an IORequest structure of the given size for communication thru the given port. Almost identically to the amiga.lib CreateExtIO() except that the memory for the structure is taken from the ViNCEd memory pool. If the handler process quits, the memory will be given back, but THE IOREQUEST WILL NOT BE ABORTED. This is still up to you. You still MUST call PoolDeleteExtIO() to get rid of it. INPUTS cn - a pointer to the struct ViNCWindow the memory has to be taken from. MUST be locked before this function is called. port - the reply port for this IORequest size - the size of the IORequest, e.g. sizeof(struct timerequest) RESULTS a pointer to an initialized IORequest structure or NULL on failure. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. If the handler process quits, the memory will be given back, but THE IOREQUEST WILL NOT BE ABORTED. This is still up to you. You still MUST call PoolDeleteExtIO() to get rid of it. SEE ALSO PoolCreateStdIO(), PoolDeleteExtIO(), CreateExtIO(), CreateIORequest(), exec/io.h vnc.library/PoolCreateStdIO vnc.library/PoolCreateStdIO NAME PoolCreateStdIO - build an IORequest from the editor memory pool SYNOPSIS io = PoolCreateStdIO ( cn , port ) d0 a5 a1 struct IOStdReq * PoolCreateStdIO ( struct ViNCWindow * , struct MsgPort * ) io = PoolCreateStdIO_CN ( port ) d0 a1 struct IOStdReq * PoolCreateStdIO_CN ( struct MsgPort * ) FUNCTION Build an IOStdReq structure of the given size for communication thru the given port. Almost identically to the amiga.lib CreateStdIO() except that the memory for the structure is taken from the ViNCEd memory pool. If the handler process quits, the memory will be given back, but THE IOSTDREQ WILL NOT BE ABORTED. This is still up to you. You still MUST call PoolDeleteStdIO() to get rid of it. INPUTS cn - a pointer to the struct ViNCWindow the memory has to be taken from. MUST be locked before this function is called. port - the reply port for this IOStdReq. RESULTS a pointer to an initialized IORequest structure or NULL on failure. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. If the handler process quits, the memory will be given back, but THE IOREQUEST WILL NOT BE ABORTED. This is still up to you. You still MUST call PoolDeleteStdIO() to get rid of it. This function is identical to PoolCreateExtIO() except that the size parameter is always set to sizeof(struct IOStdReq). SEE ALSO PoolCreateExtIO(), PoolDeleteStdIO(), CreateStdIO(), CreateIORequest(), exec/io.h vnc.library/PoolDeleteExtIO vnc.library/PoolDeleteExtIO NAME PoolDeleteExtIO - delete an IORequest structure SYNOPSIS PoolDeleteExtIO ( cn , io ) a5 a1 VOID PoolDeleteExtIO ( struct ViNCWindow * , struct IORequest * ) PoolDeleteExtIO_CN ( io ) a1 VOID PoolDeleteExtIO_CN ( struct IORequest * ) FUNCTION Deallocate and release a previously build struct IORequest from PoolCreateExtIO(). Almost identically to the amiga.lib DeleteExtIO() except that this call uses the ViNCEd memory pool. THE IOSTDREQ WILL NOT BE ABORTED. This is still up to you. INPUTS cn - a pointer to the struct ViNCWindow the memory has to be taken from. MUST be locked before this function is called. io - a pointer to a struct IORequest allocated with PoolCreateExtIO() before. RESULTS NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. SEE ALSO PoolCreateExtIO(), PoolDeleteStdIO(), DeleteStdIO(), DeleteIORequest(), exec/io.h vnc.library/PoolDeleteStdIO vnc.library/PoolDeleteStdIO NAME PoolDeleteStdIO - delete an IOStdReq structure SYNOPSIS PoolDeleteStdIO ( cn , io ) a5 a1 VOID PoolDeleteStdIO ( struct ViNCWindow * , struct IORequest * ) PoolDeleteStdIO_CN ( io ) a1 VOID PoolDeleteStdIO_CN ( struct IORequest * ) FUNCTION Deallocate and release a previously build struct IOStdReq from PoolCreateStdIO(). Almost identically to the amiga.lib DeleteStdIO() except that this call uses the ViNCEd memory pool. THE IOSTDREQ WILL NOT BE ABORTED. This is still up to you. INPUTS cn - a pointer to the struct ViNCWindow the memory has to be taken from. MUST be locked before this function is called. io - a pointer to a struct IORequest allocated with PoolCreateStdIO() before. RESULTS NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. This function is currently identical to PoolDeleteExtIO(). SEE ALSO PoolCreateExtIO(), PoolDeleteStdIO(), DeleteExtIO(), DeleteIORequest(), exec/io.h vnc.library/PoolCreatePort vnc.library/PoolCreatePort NAME PoolCreatePort - build a message port from the ViNCEd memory pool. SYNOPSIS msgport = PoolCreatePort ( cn , name , pri ) d0 a5 a0 d0 struct MsgPort * PoolCreatePort ( struct ViNCWindow * , char * , BYTE ) msgport = PoolCreatePort_CN ( name , pri ) d0 a0 d0 struct MsgPort * PoolCreatePort_CN ( char * , BYTE ) FUNCTION Builds a message port from the ViNCEd memory pool of the given priority and name, and if the name paramter is non-NULL, add this pool to the database of the public ports. INPUTS cn - a pointer to the struct ViNCWindow * to take the memory from. MUST be locked with LockWindow() before. name - a name parameter. If non-NULL, the port will be added to the public port list. The name itself will not be copied, you've to keep it constant for the lifetime of the port. pri - a priority for the port. It will be enqueued according to this priority into the public port list if the name parameter is non-NULL. RESULTS a pointer to an initialized and ready-to-use port structure, or NULL on failure. If name is non-NULL, this port will have been added to the public port list. NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. Even though the memory for the port is taken from the ViNCEd memory pool and is therefore released when the handler process shuts down, this does not mean that the port is removed from the public port list or the signal bit of this port is released at this time. You STILL have to call PoolDeletePort() to get rid of this port, and the signal bit allocated for this port. The name of the port will not be copied. If you want to place this in the memory pool, too, then use AllocEdMem() to allocate ViNCEd memory for it and copy the name over manually. However, it's in most cases good enough just to keep the name valid for the lifetime of the port. SEE ALSO PoolDeletePort(), CreatePort(), CreateMsgPort(), exec/ports.h vnc.library/PoolDeletePort vnc.library/PoolDeletePort NAME PoolDeletePort - dispose a message port of the ViNCEd memory pool. SYNOPSIS PoolDeletePort ( cn , port ) a5 a1 VOID PoolDeletePort ( struct ViNCWindow * , struct MsgPort * ) PoolDeletePort_CN ( port ) a1 VOID PoolDeletePort_CN ( struct MsgPort * ) FUNCTION Deletes a message port from the ViNCEd memory pool previously created with PoolCreatePort(). Removes the message port from the public port list if the port has a non-NULL name, and de- allocated the signal bit allocated for the port. INPUTS cn - a pointer to the struct ViNCWindow * to take the memory from. MUST be locked with LockWindow() before. port - the pointer to the message port to be released. MUST have been allocated with PoolCreatePort() before. RESULTS NOTES There are two forms of this function available. The first form is the "natural" library form, the second is available as a stub routine in the link libraries in the archive. It automatically provides the window pointer which must have been set by the link library function SetCNWindow() before. It is VERY IMPORTANT that you accessed control to the ViNCEd window to be modified with LockWindow() first. Even though the memory for the port is taken from the ViNCEd memory pool and is therefore released when the handler process shuts down, this does not mean that the port is removed from the public port list or the signal bit of this port is released at this time. You STILL have to call PoolDeletePort() to get rid of this port, and the signal bit allocated for this port. The port will be removed from the public port list if the name field of the port structure is non-NULL. SEE ALSO PoolCreatePort(), DeletePort(), DeleteMsgPort(), exec/ports.h vnc.library/VNCFOpen vnc.library/VNCFOpen NAME VNCFOpen - open a buffered stream SYNOPSIS file = VNCFOpen ( name , flags , bufsize ) d0 a0 d0 d1 FileHandle * VNCFOpen ( char * , UBYTE , UWORD ) FUNCTION Open a file for buffered I/O. INPUTS name - filename of the file to open flags - the access mode of the file. The following flags can be set: #define FHMOD_APPEND (1<<0) /* append to end of file */ #define FHMOD_READ (1<<2) /* open for reading */ #define FHMOD_WRITE (1<<3) /* open for writing */ #define FHMOD_RECORD (1<<6) /* record-oriented IO */ #define FHMOD_NONUL (1<<7) /* don't write NULs on record IO */ bufsize - the size of the I/O buffer RESULTS a pointer to a filehandle. This is NOT a Dos type file handle, but a ViNCEd specific structure. It looks like this: typedef struct { BPTR fh_DOSHandle; /* BPTR to DOS file structure */ void *fh_Buffer; /* buffer itself */ UWORD fh_BufferLength; /* its length */ UWORD fh_BufferContents; /* # of valid bytes */ UWORD fh_BufferPos; /* pos of fileptr in buffer */ UWORD fh_DOSOffset; /* offset of buffer in total */ UBYTE fh_Mode; /* open mode, see above */ UBYTE fh_Flags; /* additional flags, internal */ char fh_RecordSep1; /* record seperator, as LF or NUL */ char fh_RecordSep2; /* a second one... */ ULONG fh_FilePointer; /* absolute position in file */ } FileHandle; NOTES The ViNCEd buffered I/O functions are more advanced than the DOS buffered I/O. First, the size of the buffer is adjustable. Second, the functions do not inherit some BCPL illnesses and are therefore faster. Third, they are more flexible. Flipping between reading, writing and seeking does no longer require a buffer flush. They provide a record oriented I/O with a configurable record field separator. SEE ALSO VNCFClose(), Open(), vnc/io.h vnc.library/VNCFClose vnc.library/VNCFClose NAME VNCFClose - close a buffered stream SYNOPSIS ok = VNCFClose ( file ) d0 a0 BOOL VNCFClose ( FileHandle * ) FUNCTION Close a buffered stream. INPUTS file - the filehandle to close. NOT a DOS FileHandle. RESULTS a boolean success failure indicator. There's currently not much that can be done in case of a failure. While it is not "safe" to ignore the return code, there's not much more you can do in that case. NOTES BUGS there's nothing that can be done in case of a failure. Same goes btw. for the Close() function of the DOS library. SEE ALSO VNCFOpen(), Close(), vnc/io.h vnc.library/VNCFRead vnc.library/VNCFRead NAME VNCFRead - read buffered from a stream SYNOPSIS bytes = VNCFRead ( file , buffer , size ) d0 a0 a1 d1 LONG VNCFRead ( FileHandle * , void * , ULONG ) FUNCTION Read the specified number of bytes from the stream to the buffer. INPUTS file - the filehandle to read from. NOT a DOS FileHandle. buffer - the buffer to read to. size - the number of bytes to read. In record I/O, the maximal number of characters to read, the function will stop reading as soon as a record separator is found. RESULTS the number of bytes read, or -1 in case of a failure. NOTES the buffer size is passed in d1, not in d0. SEE ALSO VNCFOpen(), VNCFWrite(), Read(), vnc/io.h vnc.library/VNCFWrite vnc.library/VNCFWrite NAME VNCFWrite -write buffered to a stream SYNOPSIS bytes = VNCFWrite ( file , buffer , size ) d0 a0 a1 d1 LONG VNCFWrite ( FileHandle * , void * , ULONG ) FUNCTION Write the specified number of bytes to the stream from the buffer. INPUTS file - the filehandle to write to. NOT a DOS FileHandle. buffer - the buffer to write from. size - the number of bytes to write. The buffer will be flushed in record I/O as soon as a record separator is found. You may specify explicitly NOT to write the primary separator (usually ASCII NUL). RESULTS the number of bytes written, or -1 in case of a failure. NOTES the buffer size is passed in d1. SEE ALSO VNCFOpen(), VNCFRead(), Write(), vnc/io.h vnc.library/VNCOneRequester vnc.library/VNCOneRequester NAME VNCOneRequester - display a failure requester SYNOPSIS VNCOneRequester ( body ) a0 VOID VNCOneRequester ( char * ) FUNCTION Format the given prompt and build a requester with the supplied body with a (localized, though) "Cancel" button. INPUTS body - the body text of the requester. RESULTS NOTES This function uses the old "auto" requesters of intuition for compatibility to Os 1.2/1.3. However, it is likely that the backwards compatibility will be removed in ViNCEd version 3.70. Don't expect too much from this function, especially in a Os 1.3 environment. It will *try* to format and center the text and will break the text in several lines, enlarging the requester if required, but not much more. If the text is too long, its too long. Especially, do NOT pass in body texts longer than eight lines. The lines in the body text may be separated with LF, or LF and CR. SEE ALSO VNCTwoRequester(), AutoRequest() vnc.library/VNCTwoRequester vnc.library/VNCTwoRequester NAME VNCTwoRequester - display an O.K./Cancel requester SYNOPSIS ok = VNCTwoRequester ( body ) a0 BOOL VNCTwoRequester ( char * ) FUNCTION Format the given prompt and build a requester with the supplied body with two buttons, "O.K." and "Cancel", which will be localized. INPUTS body - the body text of the requester. RESULTS non-NULL if the user selected "O.K.", FALSE otherwise. NOTES This function uses the old "auto" requesters of intuition for compatibility to Os 1.2/1.3. However, it is likely that the backwards compatibility will be removed in ViNCEd version 3.70. Don't expect too much from this function, especially in a Os 1.3 environment. It will *try* to format and center the text and will break the text in several lines, enlarging the requester if required, but not much more. If the text is too long, its too long. Especially, do NOT pass in body texts longer than eight lines. The lines in the body text may be separated with LF, or LF and CR. SEE ALSO VNCOneRequester(), AutoRequest() vnc.library/GetHistory vnc.library/GetHistory NAME GetHistory - load the command history from a file SYNOPSIS error = GetHistory ( file , flags ) d0 a0 d0 LONG GetHistory ( char * , ULONG ) FUNCTION Load the command history from a file. INPUTS file - the name of the file to load the buffer from. flags - currently only one bit is defined: #define BMNF_CHECKBREAK_BIT 0L #define BMNF_CHECKBREAK_MASK (1L<<0) If this bit is defined, the function will check for a ^C signal bit and abort loading if the bit is received. RESULTS Zero for success or a failure code: #define BMNC_BREAKABORT 1L /* canceled by ^C */ #define BMNC_OPENFAILED 2L /* file open failed */ #define BMNC_READING 3L /* read failed */ #define BMNC_WRITING 4L /* writing failed */ #define BMNC_MEMORY 5L /* out of memory */ In case of an I/O error, more detailed failure codes can be obtained by IoErr(). SEE ALSO PutHistory(), vnc/bufferio.h vnc.library/PutHistory vnc.library/PutHistory NAME PutHistory - save the command history to a file SYNOPSIS error = PutHistory ( file , flags ) d0 a0 d0 LONG PutHistory ( char * , ULONG ) FUNCTION Save the current command history to a file. INPUTS file - the name of the file to save the buffer to. flags - currently only one bit is defined: #define BMNF_CHECKBREAK_BIT 0L #define BMNF_CHECKBREAK_MASK (1L<<0) If this bit is defined, the function will check for a ^C signal bit and abort loading if the bit is received. RESULTS Zero for success or a failure code: #define BMNC_BREAKABORT 1L /* canceled by ^C */ #define BMNC_OPENFAILED 2L /* file open failed */ #define BMNC_READING 3L /* read failed */ #define BMNC_WRITING 4L /* writing failed */ #define BMNC_MEMORY 5L /* out of memory */ In case of an I/O error, more detailed failure codes can be obtained by IoErr(). SEE ALSO GetHistory(), vnc/bufferio.h vnc.library/GetScreen vnc.library/GetScreen NAME GetScreen - load the display buffer from a file SYNOPSIS error = GetScreen ( file , flags ) d0 a0 d0 LONG GetHistory ( char * , ULONG ) FUNCTION Load the display buffer from a file, and place the cursor at the end of the loaded data. INPUTS file - the name of the file to load the buffer from. flags - currently only one bit is defined: #define BMNF_CHECKBREAK_BIT 0L #define BMNF_CHECKBREAK_MASK (1L<<0) If this bit is defined, the function will check for a ^C signal bit and abort loading if the bit is received. RESULTS Zero for success or a failure code: #define BMNC_BREAKABORT 1L /* canceled by ^C */ #define BMNC_OPENFAILED 2L /* file open failed */ #define BMNC_READING 3L /* read failed */ #define BMNC_WRITING 4L /* writing failed */ #define BMNC_MEMORY 5L /* out of memory */ In case of an I/O error, more detailed failure codes can be obtained by IoErr(). SEE ALSO PutScreen(), vnc/bufferio.h vnc.library/PutScreen vnc.library/PutScreen NAME PutScreen - save the display buffer to a file SYNOPSIS error = PutScreen ( file , flags ) d0 a0 d0 LONG PutScreen ( char * , ULONG ) FUNCTION Save the display buffer to a file. INPUTS file - the name of the file to save the buffer to. flags - currently only one bit is defined: #define BMNF_CHECKBREAK_BIT 0L #define BMNF_CHECKBREAK_MASK (1L<<0) If this bit is defined, the function will check for a ^C signal bit and abort loading if the bit is received. RESULTS Zero for success or a failure code: #define BMNC_BREAKABORT 1L /* canceled by ^C */ #define BMNC_OPENFAILED 2L /* file open failed */ #define BMNC_READING 3L /* read failed */ #define BMNC_WRITING 4L /* writing failed */ #define BMNC_MEMORY 5L /* out of memory */ In case of an I/O error, more detailed failure codes can be obtained by IoErr(). SEE ALSO GetScreen(), vnc/bufferio.h vnc.library/NameOfFunction vnc.library/NameOfFunction NAME NameOfFunction - return the name of a keyboard function SYNOPSIS name = NameOfFunction ( id ) d0 d0 char * NameOfFunction ( UWORD ) FUNCTION Return the name of a keyboard function if the ID is given. INPUTS id - The ID of the keyboard function to find the name of. RESULTS the name of the keyboard function or NULL if the ID is unknown. NOTES This function does not copy the string in question, hence it returns a pointer to a string in the DATA segment of the library. Do not modify this string! This function IS NEVER localized. It returns the english names of the keyboard functions. You've to provide your own localization database for this purpose. SEE ALSO NameOfKey() vnc.library/NameOfKey vnc.library/NameOfKey NAME NameOfKey - return the name of a special keyboard key SYNOPSIS name = NameOfKey ( code ) d0 d0 char * NameOfKey ( UWORD ) FUNCTION Return the name of a keyboard key if the raw key code is given. However, this function returns only the names of "special" keyboard keys like RETURN or SHIFT, or the keys on the numeric key pad. INPUTS code - The raw key code of the key to find the name of. RESULTS the name of the key or NULL if the raw key code is unknown. NOTES This function does not copy the string in question, hence it returns a pointer to a string in the DATA segment of the library. Do not modify this string! This function IS NEVER localized. It returns the english names of the keyboard keys. Furthermore, it returns only the names of those keyboard keys that usually do not depend on the localization, i.e. "special keys" that return either control sequences or non-printable characters. SEE ALSO NameOfFunction() vnc.library/InstallGlobalHooks vnc.library/InstallGlobalHooks NAME InstallGlobalHooks - patchable Init vector SYNOPSIS InstallGlobalHooks ( cn ) a5 VOID InstallGlobalHook ( struct ViNCWindow * ) FUNCTION This function does, by itself, nothing. It is, however, called by ViNCEd as soon as a new ViNCWindow structure has been build and can therefore be used to patch it by an external program if desired. INPUTS cn - struct ViNCWindow, pointer to the ViNCEd main structure. It will be locked if this routine is called by the handler process. RESULTS nope. SEE ALSO BUGS nope. SEE ALSO vnc/Window.h